home *** CD-ROM | disk | FTP | other *** search
/ Apple Reference & Presen…on Library 1994 September / ARPLE-Sept-94-Supplement.iso / AppleSoft / System 7.5 Hands-on / Apple Guide / API / AppleGuide.h < prev   
Encoding:
C/C++ Source or Header  |  1994-04-19  |  7.0 KB  |  308 lines  |  [TEXT/MPS ]
  1. /***************************************************************************************
  2.  
  3.     File:        AppleGuide.h
  4.  
  5.     Contains:    Public interface to Apple Guide.
  6.  
  7.     Written by:    Dave Lyons and John R. Powers, III
  8.  
  9.     Copyright:    ©1994 by Apple Computer, Inc., all rights reserved.
  10.  
  11.     Change History (most recent first):
  12.     
  13.         <8>  04/04/94    JRP        Beta seed
  14.  
  15. ***************************************************************************************/
  16.  
  17. #ifndef __APPLEGUIDE__
  18. #define __APPLEGUIDE__
  19.  
  20. #ifndef __APPLEEVENTS__
  21.     #include <AppleEvents.h>
  22. #endif
  23.             
  24. #ifndef __FILES__
  25.     #include <Files.h>
  26. #endif
  27.  
  28. #ifndef __TYPES__
  29.     #include <Types.h>
  30. #endif
  31.  
  32.  
  33. // Types
  34.  
  35. typedef unsigned long  UInt32;
  36. typedef unsigned short UInt16;
  37. typedef signed   short SInt16;
  38.  
  39. typedef UInt32 AGRefNum;
  40. typedef UInt32 AGCoachRefNum;
  41. typedef UInt32 AGContextRefNum;
  42.  
  43.  
  44. typedef struct AGAppInfo
  45. {
  46.     AEEventID    eventId;
  47.     long        refCon;
  48.     void*        contextObj;        // private system field
  49. }
  50.     AGAppInfo, *AGAppInfoPtr, **AGAppInfoHdl;
  51.  
  52. typedef pascal OSErr (*CoachReplyProcPtr)(Rect* pRect,
  53.                                             Ptr name,
  54.                                             long refCon);
  55.  
  56.  
  57. typedef pascal OSErr (*ContextReplyProcPtr)(Ptr pInputData,
  58.                                             Size inputDataSize,
  59.                                             Ptr *ppOutputData,
  60.                                             Size *pOutputDataSize,
  61.                                             AGAppInfoHdl hAppInfo);
  62.  
  63. // Constants
  64.  
  65. #define gestaltAppleGuidePresent    31
  66. #define kAGDefault                    0
  67. #define kAGFrontDatabase            1
  68. #define    kAGNoMixin                    (-1)
  69.  
  70.  
  71. enum
  72. {
  73.     kAGViewFullHowdy =        1,        // Full-size Howdy
  74.     kAGViewTopicAreas =        2,        // Full-size Topic Areas
  75.     kAGViewIndex =            3,        // Full-size Index Terms
  76.     kAGViewLookFor =        4,        // Full-size Look-For (Search)
  77.     kAGViewSingleHowdy =    5,        // Single-list-size Howdy
  78.     kAGViewSingleTopics =    6        // Single-list-size Topics
  79. };
  80.  
  81.  
  82. enum
  83. {
  84.     kAGFileMain =    'help',
  85.     kAGFileMixin =    'mixn'
  86. };
  87.  
  88.  
  89. enum AGDBTypeBit        // To test against AGGetAvailableDBTypes
  90. {
  91.     kAGDBTypeBitAny =        0x00000001,
  92.     kAGDBTypeBitHelp =        0x00000002,
  93.     kAGDBTypeBitTutorial =    0x00000004,
  94.     kAGDBTypeBitShortcuts =    0x00000008,
  95.     kAGDBTypeBitAbout =        0x00000010,
  96.     kAGDBTypeBitOther =        0x00000080
  97. };
  98.  
  99.  
  100. typedef UInt16 AGStatus;
  101. enum                    // Returned by AGGetStatus
  102. {
  103.     kAGIsNotRunning,
  104.     kAGIsSleeping,
  105.     kAGIsActive
  106. };
  107.  
  108.  
  109. typedef UInt16 AGWindowKind;
  110. enum                    // Returned by AGGetFrontWindowKind
  111. {
  112.     kAGNoWindow,
  113.     kAGAccessWindow,
  114.     kAGPresentationWindow
  115. };
  116.  
  117. // Error Codes
  118.  
  119. typedef SInt16 AGErr;    // Not an enum, because other OSErrs are valid.
  120. enum                    // Apple Guide error codes
  121. {
  122.     // -------------------- Apple event reply codes
  123.  
  124.     kAGErrUnknownEvent =        -2900,
  125.     kAGErrCantStartup =            -2901,
  126.     kAGErrNoAccWin =            -2902,
  127.     kAGErrNoPreWin =            -2903,
  128.     kAGErrNoSequence =            -2904,
  129.     kAGErrNotOopsSequence =        -2905,
  130.     kAGErrReserved06 =            -2906,
  131.     kAGErrNoPanel =                -2907,
  132.     kAGErrContentNotFound =        -2908,
  133.     kAGErrMissingString =        -2909,
  134.     kAGErrInfoNotAvail =        -2910,
  135.     kAGErrEventNotAvailable =    -2911,
  136.     kAGErrCannotMakeCoach =        -2912,
  137.     kAGErrSessionIDsNotMatch =    -2913,
  138.     kAGErrMissingDatabaseSpec =    -2914,
  139.  
  140.     // -------------------- Coach's Chalkboard reply codes
  141.  
  142.     kAGErrItemNotFound =            -2925,
  143.     kAGErrBalloonResourceNotFound =    -2926,
  144.     kAGErrChalkResourceNotFound =    -2927,
  145.     kAGErrChdvResourceNotFound =    -2928,
  146.     kAGErrAlreadyShowing =            -2929,
  147.     kAGErrBalloonResourceSkip =        -2930,
  148.     kAGErrItemNotVisible =            -2931,
  149.     kAGErrReserved32 =                -2932,
  150.     kAGErrNotFrontProcess =            -2933,
  151.     kAGErrMacroResourceNotFound =    -2934,
  152.  
  153.     // -------------------- API reply codes
  154.  
  155.     kAGErrAppleGuideNotAvailable =    -2951,
  156.     kAGErrCannotInitCoach =            -2952,
  157.     kAGErrCannotInitContext =        -2953,
  158.     kAGErrCannotOpenAliasFile =        -2954,
  159.     kAGErrNoAliasResource =            -2955,
  160.     kAGErrDatabaseNotAvailable =    -2956,
  161.     kAGErrDatabaseNotOpen =         -2957,
  162.     kAGErrMissingAppInfoHdl =        -2958,
  163.     kAGErrMissingContextObject =    -2959,
  164.     kAGErrInvalidRefNum =            -2960,
  165.     kAGErrDatabaseOpen =            -2961,
  166.     kAGErrInsufficientMemory =        -2962
  167.  
  168. };
  169.  
  170. // Events
  171.  
  172. typedef UInt32 AGEvent;    // Not an enum because we want to make assignments.
  173. enum                    // Handy events for AGGeneral.
  174. {
  175.         // Panel actions (Require a presentation window).
  176.     kAGEventDoCoach =            'doco',
  177.     kAGEventDoHuh =                'dhuh',
  178.     kAGEventGoNext =            'gonp',
  179.     kAGEventGoPrev =            'gopp',
  180.     kAGEventHidePanel =            'pahi',
  181.     kAGEventReturnBack =        'gobk',
  182.     kAGEventShowPanel =            'pash',
  183.     kAGEventTogglePanel =        'patg'
  184. };
  185.  
  186. // Functions
  187.  
  188. #ifdef __cplusplus
  189. extern "C" {
  190. #endif
  191.  
  192.     // AGClose
  193.     // Close the database associated with the AGRefNum.
  194.  
  195. pascal AGErr AGClose(AGRefNum *refNum)
  196.  = {0x7011,0xAA6E};
  197.  
  198.     // AGGeneral
  199.     // Cause various events to happen.
  200.  
  201. pascal AGErr AGGeneral(AGRefNum refNum, AGEvent theEvent)
  202.  = {0x700D,0xAA6E};
  203.  
  204.     // AGGetAvailableDBTypes
  205.     // Return the database types available for this application.
  206.  
  207. pascal UInt32 AGGetAvailableDBTypes(void)
  208.  = {0x7008,0xAA6E};
  209.  
  210.     // AGGetFrontWindowKind
  211.     // Return the kind of the front window.
  212.  
  213. pascal AGWindowKind AGGetFrontWindowKind(AGRefNum refNum)
  214.  = {0x700C,0xAA6E};
  215.  
  216.     // AGGetFSSpec
  217.     // Return the FSSpec for the AGRefNum.
  218.  
  219. pascal AGErr AGGetFSSpec(AGRefNum refNum, FSSpec* fileSpec)
  220.  = {0x700F,0xAA6E};
  221.  
  222.     // AGGetStatus
  223.     // Return the status of Apple Guide.
  224.  
  225. pascal AGStatus AGGetStatus(void)
  226.  = {0x7009,0xAA6E};
  227.  
  228.     // AGInstallCoachHandler
  229.     // Install a Coach object location query handler.
  230.  
  231. pascal AGErr AGInstallCoachHandler(CoachReplyProcPtr coachReplyProc, long refCon,
  232.         AGCoachRefNum *resultRefNum)
  233.  = {0x7012,0xAA6E};
  234.  
  235.     // AGInstallContextHandler
  236.     // Install a context check query handler.
  237.  
  238. pascal AGErr AGInstallContextHandler(ContextReplyProcPtr contextReplyProc,
  239.         AEEventID eventID, long refCon, AGContextRefNum *resultRefNum)
  240.  = {0x7013,0xAA6E};
  241.  
  242.     // AGIsDatabaseOpen
  243.     // Return true if the database associated with the AGRefNum is open.
  244.  
  245. pascal Boolean AGIsDatabaseOpen(AGRefNum refNum)
  246.  = {0x7006,0xAA6E};
  247.  
  248.     // AGOpen
  249.     // Open a guide database.
  250.  
  251. pascal AGErr AGOpen(FSSpec *fileSpec, UInt32 flags, Handle mixinControl,
  252.                         AGRefNum *resultRefNum)
  253.  = {0x7001,0xAA6E};
  254.  
  255.     // AGOpenWithSearch
  256.     // Open a guide database and preset a search string.
  257.  
  258. pascal AGErr AGOpenWithSearch(FSSpec *fileSpec, UInt32 flags, Handle mixinControl,
  259.                                 ConstStr255Param searchString,
  260.                                 AGRefNum *resultRefNum)
  261.  = {0x7002,0xAA6E};
  262.  
  263.     // AGOpenWithSequence
  264.     // Open a guide database and display a presentation window sequence.
  265.  
  266. pascal AGErr AGOpenWithSequence(FSSpec *fileSpec, UInt32 flags, Handle mixinControl,
  267.                                 short sequenceID,
  268.                                 AGRefNum *resultRefNum)
  269.  = {0x7004,0xAA6E};
  270.  
  271.     // AGOpenWithView
  272.     // Open a guide database and override the default view.
  273.  
  274. pascal AGErr AGOpenWithView(FSSpec *fileSpec, UInt32 flags, Handle mixinControl,
  275.                                 short viewNum,
  276.                                 AGRefNum *resultRefNum)
  277.  = {0x7005,0xAA6E};
  278.  
  279.     // AGQuit
  280.     // Make Apple Guide quit.
  281.  
  282. pascal AGErr AGQuit(void)
  283.  = {0x7010,0xAA6E};
  284.  
  285.     // AGRemoveCoachHandler
  286.     // Remove the Coach object location query handler.
  287.  
  288. pascal AGErr AGRemoveCoachHandler(AGCoachRefNum *resultRefNum)
  289.  = {0x7014,0xAA6E};
  290.  
  291.     // AGRemoveContextHandler
  292.     // Remove the context check query handler.
  293.  
  294. pascal AGErr AGRemoveContextHandler(AGContextRefNum *resultRefNum)
  295.  = {0x7015,0xAA6E};
  296.  
  297.     // AGStart
  298.     // Start up Apple Guide in the background.
  299.  
  300. pascal AGErr AGStart(void)
  301.  = {0x700A,0xAA6E};
  302.  
  303. #ifdef __cplusplus
  304. }
  305. #endif
  306.  
  307. #endif // __APPLEGUIDE__
  308.